P0–P2 polish: screenshots, sample report, Limitations, Contact, sister cross-links#1
Merged
Merged
Conversation
…r cross-links
The existing 1,072-line README is the most thorough among all author's repos.
This PR adds what was missing without rewriting the strong content already there.
Added (preserving everything that was already strong)
- Two real-world bot screenshots in a "What it looks like" gallery placed right
after badges, before the Table of Contents — readers see what the bot
actually does before reading the architecture
- 01-onboarding-and-vpn.webp — three-screen onboarding flow (greeting,
privacy disclaimer, VPN-client picker)
- 02-scan-and-report-delivery.webp — three-screen scan flow (start,
VPN-key delivery modes, final report with HTML attachment)
- Sample scan report in two formats:
- docs/reports/sample-scan-report.md — translated and anonymised real
report (3 CRITICAL findings: SSH/Telnet/RTSP, 6 HIGH-severity threat
IPs, traffic stats, recommendations) — Beginner-level rendering
- docs/reports/sample-scan-report.html — same content as standalone
HTML with inline dark-theme CSS, mobile-friendly — matches the file
format the bot actually delivers
- Limitations & known failure modes section — 8 honest constraints
(encrypted-payload blindness, JA3 evasion, detection lag, mobile-only,
network-side only, VPN-trust requirement, false positives, no on-device
remediation) — critical for a security tool's credibility
- Contact section with 4 explicit channels: live bot, Telegram for general,
GitHub Issues for bugs/rules, email for security researchers /
responsible disclosure / press / commercial
- Related — Claude Code ecosystem section cross-linking to all 7 sister
repos by the same author (anti-regression-setup, ai-context-hierarchy,
claude-statusline, notebooklm-claude-workflows, lingua-companion,
diabot, ghost-showcase)
- Author signature expanded — full name (Nick Podolyak) + GitHub / Habr /
dev.to / Telegram links — matches sister-repo standard
- Three new badges: Stars, Validate CI, "@secure_scanbot LIVE"
- CHANGELOG.md (Keep a Changelog) reconstructing showcase history
(0.1.0 initial → 0.2.0 this PR) plus inline bot v2.3 changes
- CONTRIBUTING.md with Phase-2 readiness priorities (detection rules,
manufacturer telemetry mapping, locales, Docker hardening, iOS rules,
STIX2/MISP integrations) and explicit responsible-disclosure clause
- .github/workflows/validate.yml — LICENSE/CHANGELOG presence, every
docs/* asset referenced from READMEs exists, HTML samples parse,
internal Markdown links resolve, screenshot files are non-empty
- README.ru.md mirrored: same screenshots gallery, sample-report
callout, Limitations, Contacts, Related, expanded author
Operational fix (separately, on production VPS)
- security-scanner-bot.service was crash-looping with status=203/EXEC
since 2026-04-15 06:46 UTC because /root/security-scanner/venv/ had
been removed from disk. systemd attempted 170,678 restarts before
this fix. The venv has been recreated, dependencies reinstalled
(aiogram 3.4.1, aiohttp 3.9.3, aiosqlite 0.19.0, nest_asyncio, plus
the analysis stack), and the service is now active polling. Bot is
live again at @secure_scanbot. Documented in CHANGELOG 0.2.0.
Excluded (deliberately)
- No rewrite of the existing 1,072-line README content — it was already
the strongest among all author's repos (origin story, 4-layer detection
engine, comparison table, real case study, AI adaptive reports). This
PR is additive, not destructive.
- Default branch rename master→main deferred — invasive, affects
external bookmarks
- awesome-claude-code submission — channel locked for non-collaborators
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The existing 1,072-line README is the most thorough among all author's repos (origin story, 4-layer detection engine, comparison vs MVT/PiRogue/AV, real-world Xiaomi case study, AI adaptive reports, Suricata/Zeek docs). This PR is additive, not destructive — it adds what was missing while preserving everything strong.
Plus a separate operational fix that landed on production along the way.
What's added
Screenshots gallery (right after badges)
01-onboarding-and-vpn.webp— three-screen onboarding flow (greeting, privacy disclaimer "we don't read messages — only what your phone connects to", VPN-client picker)02-scan-and-report-delivery.webp— three-screen scan flow (start, two VPN-key delivery modes, final report)Sample scan report (two formats)
docs/reports/sample-scan-report.md— anonymised real report from 2026-03-16 with 3 CRITICAL findings (SSH / Telnet / RTSP — strong indicators of remote-control implants) and 6 HIGH-severity threat-intel IPsdocs/reports/sample-scan-report.html— same data as standalone HTML with inline dark-theme CSS — matches the format the bot actually deliversLimitations & known failure modes
8 honest constraints — encrypted-payload blindness, JA3 evasion, detection lag, mobile-only scope, network-side only, VPN-trust requirement, false positives, no on-device remediation. Critical for a security tool's credibility.
Contact section
4 explicit channels — live bot, Telegram for general, GitHub Issues for bugs/rules, email for security researchers / responsible disclosure / press / commercial.
Related — Claude Code ecosystem
Cross-links to all 7 sister repos by the same author.
CI + meta
CHANGELOG.mdreconstructing showcase historyCONTRIBUTING.mdwith Phase-2 readiness priorities + explicit responsible-disclosure clause.github/workflows/validate.yml— link checker, HTML parse, asset existenceREADME.ru.md mirrored
All new sections translated.
Operational fix (separate from this PR, already applied on VPS)
security-scanner-bot.servicehad been crash-looping (status=203/EXEC) since 2026-04-15 06:46 UTC because/root/security-scanner/venv/was removed from disk. systemd attempted 170,678 restarts before the fix. The venv has been recreated, dependencies reinstalled (aiogram 3.4.1, aiohttp 3.9.3, aiosqlite 0.19.0, nest_asyncio + analysis stack), service is nowactive (running). Bot is live again at @secure_scanbot. Documented inCHANGELOG.md0.2.0.Excluded (deliberately)
master → maindeferred (affects external bookmarks)Test plan
LICENSEandCHANGELOG.mdpresentdocs/*assets referenced from both READMEs exist🤖 Generated with Claude Code